GitHub CLI (gh)

Expert guidance for GitHub CLI operations and workflows.

Installation & Setup

bash
1# Login to GitHub
2gh auth login
3
4# Check authentication status
5gh auth status
6
7# Configure git to use gh as credential helper
8gh auth setup-git

Pull Requests

Creating PRs

bash
1# Create PR interactively
2gh pr create
3
4# Create PR with title and body
5gh pr create --title "Add feature" --body "Description"
6
7# Create PR to specific branch
8gh pr create --base main --head feature-branch
9
10# Create draft PR
11gh pr create --draft
12
13# Create PR from current branch
14gh pr create --fill  # Uses commit messages

Viewing PRs

bash
1# List PRs
2gh pr list
3
4# List my PRs
5gh pr list --author @me
6
7# View PR details
8gh pr view 123
9
10# View PR in browser
11gh pr view 123 --web
12
13# View PR diff
14gh pr diff 123
15
16# Check PR status
17gh pr status

Managing PRs

bash
1# Checkout PR locally
2gh pr checkout 123
3
4# Review PR
5gh pr review 123 --approve
6gh pr review 123 --comment --body "Looks good!"
7gh pr review 123 --request-changes --body "Please fix X"
8
9# Merge PR
10gh pr merge 123
11gh pr merge 123 --squash
12gh pr merge 123 --rebase
13gh pr merge 123 --merge
14
15# Close PR
16gh pr close 123
17
18# Reopen PR
19gh pr reopen 123
20
21# Ready draft PR
22gh pr ready 123

PR Checks

bash
1# View PR checks
2gh pr checks 123
3
4# Watch PR checks
5gh pr checks 123 --watch

Issues

Creating Issues

bash
1# Create issue interactively
2gh issue create
3
4# Create issue with title and body
5gh issue create --title "Bug report" --body "Description"
6
7# Create issue with labels
8gh issue create --title "Bug" --label bug,critical
9
10# Assign issue
11gh issue create --title "Task" --assignee @me

Viewing Issues

bash
1# List issues
2gh issue list
3
4# List my issues
5gh issue list --assignee @me
6
7# List by label
8gh issue list --label bug
9
10# View issue details
11gh issue view 456
12
13# View in browser
14gh issue view 456 --web

Managing Issues

bash
1# Close issue
2gh issue close 456
3
4# Reopen issue
5gh issue reopen 456
6
7# Edit issue
8gh issue edit 456 --title "New title"
9gh issue edit 456 --add-label bug
10gh issue edit 456 --add-assignee @user
11
12# Comment on issue
13gh issue comment 456 --body "Update"

Repository Operations

Repository Info

bash
1# View repository
2gh repo view
3
4# View in browser
5gh repo view --web
6
7# Clone repository
8gh repo clone owner/repo
9
10# Fork repository
11gh repo fork owner/repo
12
13# List repositories
14gh repo list owner

Repository Management

bash
1# Create repository
2gh repo create my-repo --public
3gh repo create my-repo --private
4
5# Delete repository
6gh repo delete owner/repo
7
8# Sync fork
9gh repo sync owner/repo
10
11# Set default repository
12gh repo set-default

Workflows & Actions

Viewing Workflows

bash
1# List workflows
2gh workflow list
3
4# View workflow runs
5gh run list
6
7# View specific run
8gh run view 789
9
10# Watch run
11gh run watch 789
12
13# View run logs
14gh run view 789 --log

Managing Workflows

bash
1# Trigger workflow
2gh workflow run workflow.yml
3
4# Cancel run
5gh run cancel 789
6
7# Rerun workflow
8gh run rerun 789
9
10# Download artifacts
11gh run download 789

Releases

Creating Releases

bash
1# Create release
2gh release create v1.0.0
3
4# Create release with notes
5gh release create v1.0.0 --notes "Release notes"
6
7# Create release with files
8gh release create v1.0.0 dist/*.tar.gz
9
10# Create draft release
11gh release create v1.0.0 --draft
12
13# Generate release notes automatically
14gh release create v1.0.0 --generate-notes

Managing Releases

bash
1# List releases
2gh release list
3
4# View release
5gh release view v1.0.0
6
7# Download release assets
8gh release download v1.0.0
9
10# Delete release
11gh release delete v1.0.0

Gists

bash
1# Create gist
2gh gist create file.txt
3
4# Create gist from stdin
5echo "content" | gh gist create -
6
7# List gists
8gh gist list
9
10# View gist
11gh gist view <gist-id>
12
13# Edit gist
14gh gist edit <gist-id>
15
16# Delete gist
17gh gist delete <gist-id>

Advanced Features

Aliases

bash
1# Create alias
2gh alias set pv "pr view"
3gh alias set bugs "issue list --label bug"
4
5# List aliases
6gh alias list
7
8# Use alias
9gh pv 123

API Access

bash
1# Make API call
2gh api repos/:owner/:repo/issues
3
4# With JSON data
5gh api repos/:owner/:repo/issues -f title="Bug" -f body="Description"
6
7# Paginated results
8gh api --paginate repos/:owner/:repo/issues

Extensions

bash
1# List extensions
2gh extension list
3
4# Install extension
5gh extension install owner/gh-extension
6
7# Upgrade extensions
8gh extension upgrade --all

Common Workflows

Code Review Workflow

bash
1# List PRs assigned to you
2gh pr list --assignee @me
3
4# Checkout PR for testing
5gh pr checkout 123
6
7# Run tests, review code...
8
9# Approve PR
10gh pr review 123 --approve --body "LGTM!"
11
12# Merge PR
13gh pr merge 123 --squash

Quick PR Creation

bash
1# Create feature branch, make changes, commit
2git checkout -b feature/new-feature
3# ... make changes ...
4git add .
5git commit -m "Add new feature"
6git push -u origin feature/new-feature
7
8# Create PR from commits
9gh pr create --fill
10
11# View PR
12gh pr view --web

Issue Triage

bash
1# List open issues
2gh issue list
3
4# Add labels to issues
5gh issue edit 456 --add-label needs-triage
6gh issue edit 456 --add-label bug
7
8# Assign issue
9gh issue edit 456 --add-assignee @developer

Configuration

bash
1# Set default editor
2gh config set editor vim
3
4# Set default git protocol
5gh config set git_protocol ssh
6
7# View configuration
8gh config list
9
10# Set browser
11gh config set browser firefox

Tips

1. Use --web flag: Open items in browser for detailed view
2. Interactive prompts: Most commands work interactively if you omit parameters
3. Filters: Use --author, --label, --state to filter lists
4. JSON output: Add --json flag for scriptable output
5. Template repos: Use gh repo create --template for templates
6. Auto-merge: Enable with gh pr merge --auto